<?
define('ROOT', $_SERVER['DOCUMENT_ROOT']);
require_once(ROOT.'/public/global.php');
require_once(ROOT.'/lang/'.$LN.'.php');
?>
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<? require_once(ROOT.'/public/ref.php'); ?>
<title>mac-rpc 远程方法调用框架</title>
<meta name="description" content="Index Page of Javascript JQuery Ext Plugins" />
<meta name="keywords" content="Javascript JQuery Ext Grid ComoBox Tree Tabs Plugin Demo Download" />
<script type="text/javascript">
$(function(){
	function adjust(){
		var de = document.documentElement
			, ch = de.clientHeight, cw = de.clientWidth;
		$('#body').width(cw - 16);
	}
	$(window).resize(adjust);
	adjust();
});
</script>
</head>
<body>
<? require_once(ROOT.'/public/head.php'); ?>
<div id="body">
	<div class="dir">
<? require_once('./dir.php'); ?>
	</div>
	<div class="main">
		<div id="nav">
			<div id="nav_path">
				<a href="<?=$LP?>">Home</a>
				&gt;
				<a href="<?=$LP?>mac/rpc">mac-rpc</a>
				&gt;
				配置
			</div>
			<div id="nav_back">
				<a href="javascript:history.back()"><?=$Msg['back']?></a>
				|
				<a href="<?=$LP?>"><?=$Msg['up']?></a> &nbsp;&nbsp;
			</div>
			<div class="clear"></div>
		</div>
<h1>mac-rpc - 配置</h1>
<h2>基本配置（conf/config.properties）</h2>
&nbsp;&nbsp;必须的配置项如下：
<xmp>
	#mac-rpc版本配置，目前固定为1.0.0
	rpc.version=1.0.0
	#指定本机IP地址，可选，仅当无法正确获取IP时配置
	#rpc.ip=20.3.6.172
	#指定监听的端口
	rpc.port=9901
</xmp>
&nbsp;&nbsp;补充说明：
<ul>
	<li>只有当两个版本相同的MAC-RPC应用才可以互相调用</li>
	<li>rpc.ip应为本机要启用的IP地址，默认是自动获取，可以不配。但当本机有多个IP地址时，自动获取的IP可能不是期望的那一个。</li>
	<li>rpc.port是必需的，并且相对同一个IP，必须是唯一的。</li>
</ul>
<h2><a name="registry"></a>注册中心配置（conf/nodes.xml）</h2>
&nbsp;&nbsp;nodes.xml通常是用来配置被作为注册中心（master）的节点。一个分布式环境至少需要一个master节点。也可以在nodes.xml中配置当前环境中的非master节点。<br/>
&nbsp;&nbsp;注意：127.0.0.1和localhost只适用于本地调试，跨机器应用时推荐配置主节点的IP或域名。
&nbsp;&nbsp;示例如下：
<xmp>
	<node address="192.168.1.11:9901" master="true" />
</xmp>
&nbsp;&nbsp;其中address应该是主节点（master）的IP地址和监听的端口，也可以是本地HOSTS中映射的主机名，也可以是域名或机器名。如果只在本机单机环境运行测试还可以是127.0.0.1或localhost。
<h2><a name="provider"></a>服务提供者配置（conf/provide.xml）</h2>
&nbsp;&nbsp;示例如下：
<xmp>
	<service group="cache" name="cacheCatalog" ref="cacheMonitor"
		interface="com.boarsoft.cache.config.CacheCatalog" version="1.0.0">
	</service>
</xmp>
&nbsp;&nbsp;除了服务四要素外，作为服务提供者配置项还有：
<ul>
	<li>ref：实现此服务的spring bean 的id，该bean必须实现指定的接口（interface），解析时会生成一个实现此接口的代理类，来调用这个bean</li>
</ul>
<h2><a name="consume"></a>服务消费者配置（conf/consume.xml）</h2>
<h3>基本配置</h3>
&nbsp;&nbsp;示例如下：<br/>
<xmp>
	<reference id="cacheCatalog" group="cache" name="cacheCatalog"
		interface="com.boarsoft.cache.config.CacheCatalog"
		version="1.0.0" timeout="3000">
	</reference>
</xmp>
&nbsp;&nbsp;除了服务四要素外，作为服务提供者配置项还有：<br/>
<ul>
	<li>id：生成的代理对象在spring中的ID，此bean必须实现指定的接口（interface），解析是会生成一个实现此接口的代理类，来调用这个bean</li>
	<li>timeout：调用此接口中所有方法的超时时间，单位：毫秒</li>
</ul>
<h3><a name="method"></a>方法配置</h3>
&nbsp;&nbsp;可以在reference标签下添加method标签，以具体修饰某个方法。<br/>
&nbsp;&nbsp;method标签不是必须的，无论是否添加method标签，当前接口中的所有方法都会被暴露。这些方法默认是以同步方法调用的它用来调用的（type=SC）。如果需要修改方法的调用方式，或者指定它的超时时间，就需要添加对应的method标签。<br/>
&nbsp;&nbsp;arg标签是method的子标签，用于确定方法的签名。对method标签来说，arg标签是必须的，它们需要与方法的参数一一对应，且是有序的。<br/>
&nbsp;&nbsp;示例如下：<br/>
<xmp>
	<reference id="demoBc1" group="demo" name="demoBc1"
		interface="com.boarsoft.sample.DemoBC" version="1.0.0" timeout="30000">
		<!-- Sync Call -->
		<method name="bcTest" type="SC" timeout="2100">
			<arg type="java.lang.String" />
			<arg type="int" />
		</method>
		<!-- Sync Broadcast -->
		<method name="bcTest" type="SB" timeout="1200">
			<arg type="java.lang.String" />
		</method>
		<!-- Async Call，demoCallback 为本地beanId，可选 -->
		<method name="asyncCallTest" type="AC" timeout="3000" callback="demoCallback">
			<arg type="java.lang.String" />
		</method>
	</reference>
</xmp>
&nbsp;&nbsp;method标签的合法属性有：<br/>
<ul>
	<li>name：方法名</li>
	<li>timeout：此方法的超时时间，此设置会覆盖reference中的设置</li>
	<li>type：方法的调用形式，详细见“RPC方法类型编号及缩写”章节，默认是同步方法调用（SC）</li>
	<li>callback：方法调用完成后，需要执行的回调对象在spring中的ID	此对象必须实现RpcCallback接口，它可以是一个普通的本地bean也可以是一远程对象的代理（一个在前面已定义的referenece）</li>
</ul>
&nbsp;&nbsp;arg标签的合法属性有：<br/>
<ul>
	<li>type：参数类名，参数的java类型</li>
</ul>
<h3><a name="methodType"></a>方法类型</h3>
&nbsp;&nbsp;MAC-RPC定义的RPC方法类型有以下几种，其中通知类型（NOTICE）总是在服务端异步执行，并返回签收应答，并不返回实际执行的结果。而异步类型（ASYNC）总是在调用方发起调用后，返回本地Future对象而不是远程的执行结果，不会阻塞当前线程。<br/> 
<xmp>
	/** SC：本地：同步调起，阻塞以等待结果；远程：同步执行，返回结果 */
	public static final short TYPE_SYNC_CALL = 0;
	/** AC，本地：同步调起，返回Future<Object>；远程：同步执行，返回结果 */
	public static final short TYPE_ASYNC_CALL = 1;
	/** SN，本地：同步调起，阻塞以等待应答；远程：异步执行，回声应答 */
	public static final short TYPE_SYNC_NOTICE = 2;
	/** AN，本地：同步调起，返回Future<Object>；远程：异步执行，回声应答 */
	public static final short TYPE_ASYNC_NOTICE = 3;
	/** SB，本地：依次调用所有服务提供者，等待拿到的所有的Future结束，返回（Map<String, Object>）； 远程：同步执行，返回结果 */
	public static final short TYPE_SYNC_BROADCAST = 4;
	/** AB，本地：依次调用所有服务提供者，直接返回拿到的所有的Future（Map<String, Future<Object>>）；远程：同步执行，返回结果 */
	public static final short TYPE_ASYNC_BROADCAST = 5;
	/** BN，本地：依次调用所有服务提供者，直接返回拿到的所有的Future（Map<String, Future<Object>>）；远程：异步执行，回声应答 */
	public static final short TYPE_BROADCAST_NOTICE = 6;
</xmp>
&nbsp;&nbsp;注：如果不希望或者不能将异步类型（ASYNC）方法的返回声明为Object，或广播方法的返回声明为Map&lt;String, Object&gt;，可以将服务提供方的接口方法返回值定义为实际的返回结果类型，而将服务消费方的接口方法返回值定义为Future&lt;实际结果类型&gt;。如果也不希望将服务消费方的接口方法返回值修为Future，则需要自行用多线程实现异步。
	</div>
</div>
<? require_once(ROOT.'/public/foot.html'); ?>
</body>
</html>
<?
$fp = ROOT.$LP.'/mac/rpc/';
output(basename(__FILE__), $fp.'config.html');
?>